<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine manual.	-*-Text-*- -->
<!-- Documentation on PACK4. -->

<div class='chapter'>4. Packages</div><p class='cindent'><!-- package -->

<div class='section'>4.1 The Need for Multiple Contexts</div>
	A Lisp program is a collection of function definitions.
The functions are known by their names, and so each must have its
own name to identify it.  Clearly a programmer must not use the same
name for two different functions.

	The Lisp machine consists of a huge Lisp environment, in which many
programs must coexist. All of the "operating system", the compiler, the
EINE editor, and a wide variety of programs are provided in the initial
environment.  Furthermore, every program which the user uses during
his session must be loaded into the same environment.  Each of these
programs is composed of a group of functions; apparently each function
must have its own distinct name to avoid conflicts.  For example, if
the compiler had a function named <font class="lisp">pull</font>, and the user loaded a program
which had its own function named <font class="lisp">pull</font>, the compiler's <font class="lisp">pull</font> would be
redefined, probably breaking the compiler.

	It would not really be possible to prevent these conflicts,
since the programs are written by many different people who could
never get together to hash out who gets the privilege of using
a specific name such as <font class="lisp">pull</font>.

	Now, if we are to enable two programs to coexist in the Lisp
world, each with its own function <font class="lisp">pull</font>, then each program must have
its own symbol named "<font class="lisp">pull</font>", because there can't be two function
definitions on the same symbol.  This means that separate "name
spaces"--mappings between names and symbols--must be provided for
them.  The package system is designed to do just that.

	Under the package system,  the author of a program or a group
of closely related programs identifies them together as a "package".
The package system associates a distinct name space with each package.

	Here is an example: suppose there are two programs named <font class="lisp">chaos</font>
and <font class="lisp">arpa</font>, for handling the Chaos net and Arpanet respectively.  The
author of each program wants to have a function called <font class="lisp">get-packet</font>,
which reads in a packet from the network (or something).  Also, each
wants to have a function called <font class="lisp">allocate-pbuf</font>, which allocates the
packet buffer.  Each "get" routine first allocates a packer buffer,
and then reads bits into the buffer; therefore, each version of
<font class="lisp">get-packet</font> should call the respective version of <font class="lisp">allocate-pbuf</font>.

	Without the package system, the two programs could not coexist
in the same Lisp environment.  But the package feature can be used to
provide a separate name space for each program.  What is required is
to declare a package named <font class="lisp">chaos</font> to contain the Chaos net program, and
another package <font class="lisp">arpa</font> to hold the Arpanet program.  When the Chaos net
program is read into the machine, its symbols would be entered in the
<font class="lisp">chaos</font> package's name space.  So when the Chaos net program's
<font class="lisp">get-packet</font> referred to <font class="lisp">allocate-pbuf</font>, the <font class="lisp">allocate-pbuf</font> in the <font class="lisp">chaos</font>
name space would be found, which would be the <font class="lisp">allocate-pbuf</font> of the
Chaos net program--the right one.  Similarly, the Arpanet program's
<font class="lisp">get-packet</font> would be read in using the <font class="lisp">arpa</font> package's name space and
would refer to the Arpanet program's <font class="lisp">allocate-pbuf</font>.

	An additional function of packages is to remember the names of
the files which constitute each program, making it easy to ask to load
or recompile all of them at once.

	To understand what is going on here, you should keep in mind
how Lisp reading and loading works.  When a file is gotten into the
Lisp machine, either by being read or by being fasloaded, the file itself
obviously cannot contain Lisp objects; it contains printed representations
of those objects.  When the reader encounters a printed representation of a symbol,
it calls <font class="lisp">intern</font> to look up that string in some name space and find
a corresponding symbol to return.  The package system arranges that the correct
name space is used whenever a file is loaded.

<div class='section'>4.2 The Organization of Name Spaces</div>
	We could simply let every name space be implemented as one
obarray, e.g. one big table of symbols.  The problem with this is
that just about every name space wants to include the whole
Lisp language: <font class="lisp">car</font>, <font class="lisp">cdr</font>, and so on should be available to every
program.  We would like to share the main Lisp system between
several name spaces without making many copies.

	Instead of making each name space be one big array,
we arrange packages in a tree.  Each package has a
"superpackage" or "parent", from which it "inherits" symbols.  Also,
each package has a table, or "obarray", of its own additional
symbols.  The symbols belonging to a package are simply those in the
package's own obarray, followed by those belonging to the
superpackage.  The root of the tree of packages is the package called
<font class="lisp">global</font>, which has no superpackage.  <font class="lisp">global</font> contains <font class="lisp">car</font> and <font class="lisp">cdr</font> and
all the rest of the standard Lisp system.  In our example, we might
have two other obarrays called <font class="lisp">chaos</font> and <font class="lisp">arpa</font>, each of which would
have <font class="lisp">global</font> as its parent.  Here is a picture of the resulting tree
structure:
<pre class="lisp">
                    global
                       |
          /----------------------------\
          |                            |
        chaos                         arpa
</pre>

	In order to make the sharing of the <font class="lisp">global</font> package work, the
<font class="lisp">intern</font> function is made more complicated than in basic Lisp.  In
addition to the string or symbol to intern, it must be told which
package to do it in.  First it searches for a symbol with the
specified name in the obarray of the specified package.  If nothing is
found there, <font class="lisp">intern</font> looks at its superpackage, and then at the
superpackage's superpackage, and so on, until the name is found or a
root package such as <font class="lisp">global</font> is reached.
When <font class="lisp">intern</font> reaches the root package, and doesn't find the symbol there either,
it decides that there is no symbol known with that name, and adds a
symbol to the originally specified package.

	Since you don't normally want to worry about specifying
packages, <font class="lisp">intern</font> normally uses the "current" package, which is the
value of the symbol <font class="lisp">package</font>.  This symbol serves the purpose of the
symbol <font class="lisp">obarray</font> in Maclisp.

	Here's how that works in the above example.  When the Chaos
net program is read into the Lisp world, the current package would be
the <font class="lisp">chaos</font> package.  Thus all of the symbols in the Chaos net program
would be interned on the <font class="lisp">chaos</font> package.  If there is a reference to
some well known global symbol such as <font class="lisp">append</font>, <font class="lisp">intern</font> would look for
"<font class="lisp">append</font>" on the <font class="lisp">chaos</font> package, not find it, look for "<font class="lisp">append</font>" on
<font class="lisp">global</font>, and find the regular Lisp <font class="lisp">append</font> symbol, and return that.  If,
however, there is a reference to a symbol which the user made up
himself (say it is called <font class="lisp">get-packet</font>), the first time he uses it,
<font class="lisp">intern</font> won't find it on either <font class="lisp">chaos</font> nor <font class="lisp">global</font>.  So <font class="lisp">intern</font> will make
a new symbol named <font class="lisp">get-packet</font>, and install it on the <font class="lisp">chaos</font> package.
When <font class="lisp">get-packet</font> is refered to later in the Chaos net program, <font class="lisp">intern</font>
will find <font class="lisp">get-packet</font> on the <font class="lisp">chaos</font> package.

	When the Arpanet program is read in, the current package would
be <font class="lisp">arpa</font> instead of <font class="lisp">chaos</font>.  When the ArpaNet program refers
to <font class="lisp">append</font>, it gets the <font class="lisp">global</font> one; that is, it shares the same one
that the Chaos net program got.  However, if it refers to <font class="lisp">get-packet</font>,
it will <font class="italic">not</font> get the same one the Chaos net program got, because
the <font class="lisp">chaos</font> package is not being searched.  Rather, the <font class="lisp">arpa</font> and <font class="lisp">global</font>
packages are getting searched.  So <font class="lisp">intern</font> will create a new <font class="lisp">get-packet</font>
and install it on the <font class="lisp">arpa</font> package.

	So what has happened is that there are two <font class="lisp">get-packet</font>s: one for
<font class="lisp">chaos</font> and one for <font class="lisp">arpa</font>.  The two programs are loaded together without name
conflicts.

<div class='section'>4.3 Shared Programs</div>
	Now, a very important feature of the Lisp machine is that of
"shared programs"; if one person writes a function to, say, print
numbers in Roman numerals, any other function can call it to print
Roman numerals.  This contrasts sharply with PDP-10 system programs,
in which Roman numerals have been independently reimplemented several
times (and the ITS filename parser several dozen times).

	For example, the routines to manipulate a robot arm might be a
separate program, residing in a package named <font class="lisp">arm</font>.  If we
have a second program called <font class="lisp">blocks</font> (the blocks world, of course)
which wanted to manipulate the arm, it would want to call functions
which are defined on the <font class="lisp">arm</font> obarray, and therefore not in <font class="lisp">blocks</font>'s
own name space.  Without special provision, there would be no way for
any symbols not in the <font class="lisp">blocks</font> name space to be part of any <font class="lisp">blocks</font>
functions.

	The colon character ("<font class="lisp">:</font>") has a special meaning to the Lisp
reader.  When the reader sees a colon preceeded by the name of a package,
it will read in the next Lisp object with <font class="lisp">package</font> bound to that package.
The way <font class="lisp">blocks</font> would
call a function named <font class="lisp">go-up</font> defined in <font class="lisp">arm</font> would be by asking to call
<font class="lisp">arm:go-up</font>, because <font class="lisp">"go-up</font> would be interned on the <font class="lisp">arm</font> package.
What <font class="lisp">arm:go-up</font> means precisely is "The symbol named <font class="lisp">go-up</font> in
the name space of the package <font class="lisp">arm</font>."

	Similarly, if the <font class="lisp">chaos</font> program wanted to refer to the <font class="lisp">arpa</font>
program's <font class="lisp">allocate-pbuf</font> function (for some reason), it would simply
call <font class="lisp">arpa:allocate-pbuf</font>.

	An important question which should occur at this point is how
the names of packages are associated with their obarrays and other
data.  This is done by means of the "refname-alist" which each package
has.  This alist associates strings called <font class="italic">reference names</font> or <font class="italic">refnames</font>
with the packages they
name.  Normally, a package's refname-alist contains an entry for each
subpackage, associating the subpackage with its name.  In addition,
every package has its own name defined as a refname, referring to
itself.  However, the user can add any other refnames, associating
them with any packages he likes.  This is useful when multiple versions
of a program are loaded into different packages.  Of course, each
package inherits its superpackage's refnames just as it does symbols.

	In our example, since <font class="lisp">arm</font> is a subpackage of <font class="lisp">global</font>, the name
<font class="lisp">arm</font> is on <font class="lisp">global</font>'s refname-alist, associated with the <font class="lisp">arm</font> package.
Since <font class="lisp">blocks</font> is also a subpackage of <font class="lisp">global</font>, when <font class="lisp">arm:go-up</font> is seen
the string "<font class="lisp">arm</font>" is found on <font class="lisp">global</font>'s refname alist.

	When you want to refer to a symbol in a package which you and
your superpackages have no refnames for--say, a subpackage named <font class="lisp">foo</font>
of a package named <font class="lisp">bar</font> which is under <font class="lisp">global</font>--you can use multiple
colons.  For example, the symbol <font class="lisp">finish</font> in that package <font class="lisp">foo</font> could be
referred to as <font class="lisp">foo:bar:finish</font>.  What happens here is that the second
name, <font class="lisp">bar</font>, is interpreted as a refname in the context of the package
<font class="lisp">foo</font>.

<div class='section'>4.4 Declaring Packages</div><p class='cindent' id='declaring-packages'><!-- declaring packages -->
<p class='cindent'><!-- package declarations -->

	Before any package can be referred to or loaded, it must be declared.
This is done with the special form <font class="lisp">package-declare</font>, which tells the package system
all sorts of things, including the name of the package, the place in the
package hierarchy for the new package to go, its estimated size, the
files which belong in it, and some of the symbols which belong in it.

  Here is a sample declaration:
<pre class="lisp">
(package-declare foo global 1000
       (("lispm;foo qfasl")
        ("lispm;bar qfasl")
        ("lispm;barmac &gt;" defs))
       (shadow array-push adjust-array-size)
       (extern foo-entry))
</pre>

	What this declaration says is that a package named <font class="lisp">foo</font> should be
created as an inferior of <font class="lisp">global</font>, the package which contains advertised
global symbols.  Its obarray should initially be large enough to hold 1000
symbols, though it will grow automatically if that isn't enough.
Unless there is a specific reason to do otherwise, you should make all
of your packages direct inferiors of <font class="lisp">global</font>.  The size you give is
increased slightly to be a good value for the hashing algorithm used.

	After the size comes the "file-alist".  The files in the <font class="lisp">foo</font> package
are "lispm;foo" and "lispm;bar", both of which should be compiled, and
"lispm;barmac", which should be read in as a text file.  In addition,
"barmac" is marked as a DEFS file, which means that the latest version of
"barmac" must always be loaded before attempting to compile or load any of
the other files.
Typically a DEFS file contains macro definitions, compiler declarations,
structure definitions, and the like.
All the source files should start with
<pre class="lisp">
(pkg-contained-in "foo")
</pre>
to help detect processing them in the wrong package.  Soon it will
automatically cause them to be processed in the right package, even if
copied under strange names.  (NOTE: <font class="lisp">pkg-contained-in</font> IS NOT IMPLEMENTED YET!
DON'T USE IT!)

	Finally, the <font class="lisp">foo</font> package "shadows" <font class="lisp">array-push</font> and <font class="lisp">adjust-array-size</font>,
and "externs" <font class="lisp">foo-entry</font>.  What shadowing means is that the <font class="lisp">foo</font> package
should have its own versions of those symbols, rather than inheriting
its superpackage's versions.  Symbols by these names will be added to the <font class="lisp">foo</font>
package even though there are symbols on <font class="lisp">global</font> already with those names.
This allows the <font class="lisp">foo</font> package to redefine
those functions for itself without redefining them in the <font class="lisp">global</font>
package for everyone else.  What externing means is that the <font class="lisp">foo</font>
package is allowed to redefine <font class="lisp">foo-entry</font> as inherited from the <font class="lisp">global</font>
package, so that it <font class="italic">is</font> redefined for everybody.  If <font class="lisp">foo</font> attempts to
redefine a function such as <font class="lisp">car</font> which is present in the <font class="lisp">global</font> package
but neither shadowed nor externed, confirmation from the user will be
requested.

	Note that externing doesn't actually put any symbols into the <font class="lisp">global</font>
package.  It just asserts permission to redefine symbols already there.
This is deliberate; the intent is to enable the maintainers of the
<font class="lisp">global</font> package to keep control over what symbols are present in it.
Because inserting a new symbol into the <font class="lisp">global</font> package can cause trouble
to unsuspecting programs which expect that symbol to be private, this is
not supposed to be done in a decentralized manner by programs written by
one user and used by another unsuspecting user.
Here is an example of the trouble that could be caused:
if there were two user programs, each with a function named <font class="lisp">move-square</font>,
and <font class="lisp">move-square</font> were put on the <font class="lisp">global</font> package, all of a sudden
the two functions would share the same symbol, resulting in a name conflict.
While all the definitions of the functions in <font class="lisp">global</font> are actually
supplied by subpackages which extern them (<font class="lisp">global</font> contains no files of
its own), the list of symbol names is centralized in one place, the file
"ai: lispm2; global &gt;", and this file is not changed without notifying everyone,
and updating the <font class="lisp">global</font> documentation.

	Certain other things may be found in the declarations of various internal system
packages.  They are arcane and needed only to compensate for the fact
that parts of those packages are actually loaded before the package
system is.  They should not be needed by any user package.

	Your package declarations should go into separate files containing
only package declarations.  Group them however you like, one to a file
or all in one file.  Such files can be read with <font class="lisp">load</font>.  It doesn't
matter what package you load them into, so use <font class="lisp">user</font>, since that has to
be safe.

	If the declaration for a package is read in twice, no harm is done.
If you edit the size to replace it with a larger one, the package will
be expanded.  If you change the file-alist, the new one will replace the
old.  At the moment, however, there is no way to change the list of
shadowings or externals;  such changes will be ignored.  Also, you can't
change the superpackage.  If you edit the superpackage name and read the
declaration in again, you will create a new, distinct package without
changing the old one.

<div class='defmac'><font class='exdent'><font class='funcname' id='package-declare'>package-declare</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>The <font class="lisp">package-declare</font> macro is used to declare a package to the package
system.  Its form is:
<pre class="lisp">
(package-declare <font class="italic">name</font> <font class="italic">superpackage</font> <font class="italic">size</font> <font class="italic">file-alist</font> <font class="italic">option-1</font> <font class="italic">option-2</font> ...)
</pre>
The interpretation of the declaration is complicated; see <a href='packd.html#declaring-packages'>this link</a>.
</div>

<div class='section'>4.5 Packages and Writing Code</div>
	The unsophisticated user need never be aware of the existence of
packages when writing his programs.  He should just load all of his
programs into the package <font class="lisp">user</font>, which is also what console type-in is
interned in.  Since all the functions which users are likely to need are
provided in the <font class="lisp">global</font> package, which is <font class="lisp">user</font>'s superpackage, they are
all available.  In this manual, functions which are not on the <font class="lisp">global</font>
package are documented with colons in their names, so typing the name
the way it is documented will work.

	However, if you are writing a generally useful tool, you should
put it in some package other than <font class="lisp">user</font>,
so that its internal functions will not conflict with
names other users use.  Whether for this reason or for any other, if you
are loading your programs into packages other than <font class="lisp">user</font> there are
special constructs that you will need to know about.

	One time when you as the programmer must be aware of the existence of
packages is when you want to use a function or variable in another
package.  To do this, write the name of the package, a colon, and then
the name of the symbol, as in <font class="lisp">eine:ed-get-defaulted-file-name</font>.  You will
notice that symbols in other packages print out that way, too.
Sometimes you may need to refer to a symbol in a package whose superior
is not <font class="lisp">global</font>.  When this happens, use multiple colons, as in
<font class="lisp">foo:bar:ugh</font>, to refer to the symbol <font class="lisp">ugh</font> in the package named <font class="lisp">bar</font> which
is under the package named <font class="lisp">foo</font>.

	Another time that packages intrude is when you use a "keyword": when
you check for <font class="lisp">eq</font>ness against a constant symbol, or pass a constant
symbol to someone else who will check for it using <font class="lisp">eq</font>.  This includes
using the symbol as either argument to <font class="lisp">get</font>.  In such cases, the usual
convention is that the symbol should reside in the <font class="lisp">user</font> package,
rather than in the package with which its meaning is associated.  To
make it easy to specify <font class="lisp">user</font>, a colon before a symbol, as in <font class="lisp">:select</font>,
is equivalent to specifying <font class="lisp">user</font> by name, as in <font class="lisp">user:select</font>.
Since the <font class="lisp">user</font> package has no subpackages, putting symbols into it will not cause
name conflicts.

	Why is this convention used?  Well, consider the function
<font class="lisp">tv-define-pc-ppr</font>, which takes any number of keyword arguments.
For example,
<pre class="lisp">
(tv-define-pc-ppr "foo" (list tvfont) 'vsp 6 'sideways-p t)
</pre>
specifies, after the two peculiar mandatory arguments, two options with
names <font class="lisp">vsp</font> and <font class="lisp">sideways-p</font> and values <font class="lisp">6</font> and <font class="lisp">t</font>.  The file containing this
function's definition is in the <font class="lisp">system-internals</font> package, but the
function is available to everyone without the use of a colon prefix
because the symbol <font class="lisp">tv-define-pc-ppr</font> is itself inherited from <font class="lisp">global</font>.
But all the keyword names, such as <font class="lisp">vsp</font>, are short and should not have
to exist in <font class="lisp">global</font>.  However, it would be a shame if all callers of
<font class="lisp">tv-define-pc-ppr</font> had to specify <font class="lisp">system-internals</font>: before the name of
each keyword.  After all, those callers can include programs loaded into
<font class="lisp">user</font>, which should by rights not have to know about packages at all.
Putting those keywords in the <font class="lisp">user</font> package solves this problem.
The correct way to type the above form would be
<pre class="lisp">
(tv-define-pc-ppr "foo" (list tvfont) ':vsp 6 ':sideways-p t)
</pre>

	Exactly when should a symbol go in <font class="lisp">user</font>?  At least, all symbols
which the user needs to be able to pass as an argument to any function
in <font class="lisp">global</font> must be in <font class="lisp">user</font> if they aren't themselves in <font class="lisp">global</font>.
Symbols used as keywords for arguments by any function should usually
be in <font class="lisp">user</font>, to keep things consistent.  However, when a program uses a
specific property name to associate its own internal memoranda with
symbols passed in from outside, the property name should belong to the
program's package, so that two programs using the same property name
in that way don't conflict.

<div class='section'>4.6 Shadowing</div>
	Suppose the user doesn't like the system <font class="lisp">nth</font> function;  he
might be a former <font class="lisp">interlisp</font> user, and expecting a completely
different meaning from it.  Were he to say <font class="lisp">(defun nth ---)</font> in his
program (call it <font class="lisp">interloss</font>) he would clobber the <font class="lisp">global</font> symbol
named "<font class="lisp">nth</font>", and so affect the "<font class="lisp">nth</font>" in everyone else's name
space. (Actually, if he had not "externed" the symbol "<font class="lisp">nth</font>", the
redefinition would be caught and the user would be warned.)

	In order to allow the <font class="lisp">interloss</font> package to have its own <font class="lisp">(defun nth
---)</font> without interfering with the rest of the Lisp environment, it
must "shadow" out the global symbol "<font class="lisp">nth</font>" by putting a new symbol
named "<font class="lisp">nth</font>" on its own obarray.  Normally, this is done by writing
<font class="lisp">(shadow nth)</font> in the declaration of the <font class="lisp">interloss</font> package.  Since
<font class="lisp">intern</font> looks on the subpackage's obarray before <font class="lisp">global</font>, it will find
the programmer's own <font class="lisp">nth</font>, and never the global one.  Since the global
one is now impossible to see, we say it has been "shadowed."

	Having shadowed <font class="lisp">nth</font>, if it is sometimes necessary to refer to the
global definition, this can be done by writing <font class="lisp">global:nth</font>.  This works
because the refname <font class="lisp">global</font> is defined in the <font class="lisp">global</font> package as a name
for the <font class="lisp">global</font> package.  Since <font class="lisp">global</font> is the superpackage of the
<font class="lisp">interloss</font> package, all refnames defined by <font class="lisp">global</font>, including <font class="lisp">"global"</font>,
are available in <font class="lisp">interloss</font>.

<div class='section'>4.7 Packages and Interning</div>
	The function <font class="lisp">intern</font> allows you to specify a package as the second
argument.  It can be specified either by giving the package object
itself, or by giving a string or symbol which is the name of the
package.  <font class="lisp">intern</font> returns three values.  The first is the interned symbol.  The
second is <font class="lisp">t</font> if the symbol is old (was already present, not just added to
the obarray).  The third is the package in which the symbol was actually
found.  This can be either the specified package or one of its
superiors.

	When you don't specify the second argument to <font class="lisp">intern</font>, the current
package, which is the value of the symbol <font class="lisp">package</font>, is used.  This
happens, in particular, when you call <font class="lisp">read</font>.  Bind the symbol <font class="lisp">package</font>
temporarily to the desired package, before calling things which call
<font class="lisp">intern</font>, when you want to specify the package.  When you do this, the
function <font class="lisp">pkg-find-package</font>, which converts a string into the package it
names, may be useful.  While most functions that use packages will do
this themselves, it is better to do it only once when <font class="lisp">package</font> is bound.
The function <font class="lisp">pkg-goto</font> sets <font class="lisp">package</font> to a package specified by a string.
You shouldn't usually need to do this, but it can be useful to "put
the keyboard inside" a package when you are debugging.

.defvar package
The value of <font class="lisp">package</font> is the current package; many functions which
take packages as optional arguments default to the value of <font class="lisp">package</font>,
including <font class="lisp">intern</font> and related functions.
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>pkg-goto <font class='italic' color='purple'>&optional pkg</font></font></font><br>
<font class="italic">pkg</font> may be a package or the name of a package.
<font class="italic">pkg</font> is made the current package.  It defaults to the <font class="lisp">user</font> package.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='pkg-bind'>pkg-bind</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>The form of the <font class="lisp">pkg-bind</font> macro is <font class="lisp">(pkg-bind <font class="italic">pkg</font> . <font class="italic">body</font>)</font>.
<font class="italic">pkg</font> may be a package or a package name.  The forms of the <font class="italic">body</font>
are evaluated sequentially with the variable <font class="lisp">package</font> bound to <font class="italic">pkg</font>.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(pkg-bind "eine"
	  (read-from-string function-name))
</pre>
</div>

	There are actually four forms of the <font class="lisp">intern</font> function:  regular <font class="lisp">intern</font>,
<font class="lisp">intern-soft</font>, <font class="lisp">intern-local</font>, and <font class="lisp">intern-local-soft</font>.  <font class="lisp">-soft</font> means that the
symbol should not be added to the package if there isn't already one;
in that case, all three values are <font class="lisp">nil</font>.  <font class="lisp">-local</font> means that the
superpackages should not be searched.  Thus, <font class="lisp">intern-local</font> can be used to
cause shadowing.  <font class="lisp">intern-local-soft</font> is a good low-level primitive for
when you want complete control of what to search and when to add symbols.
All four forms of <font class="lisp">intern</font> return the same three values, except that
the <font class="lisp">soft</font> forms return <font class="lisp">nil nil nil</font> when
the symbol isn't found.

<div class='defun'><font class='exdent'><font class='funcname'>intern <font class='italic' color='purple'>string &optional (pkg <font class="lisp">package</font>)</font></font></font><br>
<font class="lisp">intern</font> searches <font class="italic">pkg</font> and its superpackages sequentially, looking
for a symbol whose print-name is equal to <font class="italic">string</font>.  If it finds
such a symbol, it returns three values: the symbol, <font class="lisp">t</font>, and the package
on which the symbol is interned.  If it does not find one, it
creates a new symbol with a print name of <font class="italic">string</font>, and
returns the new symbol, <font class="lisp">nil</font>, and <font class="italic">pkg</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>intern-local <font class='italic' color='purple'>string &optional (pkg <font class="lisp">package</font>)</font></font></font><br>
<font class="lisp">intern</font> searches <font class="italic">pkg</font> (but <font class="italic">not</font> its superpackages), looking
for a symbol whose print-name is equal to <font class="italic">string</font>.  If it finds
such a symbol, it returns three values: the symbol, <font class="lisp">t</font>, and <font class="italic">pkg</font>
If it does not find one, it
creates a new symbol with a print name of <font class="italic">string</font>, and
returns the new symbol, <font class="lisp">nil</font>, and <font class="italic">pkg</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>intern-soft <font class='italic' color='purple'>string &optional (pkg <font class="lisp">package</font>)</font></font></font><br>
<font class="lisp">intern</font> searches <font class="italic">pkg</font> and its superpackages sequentially, looking
for a symbol whose print-name is equal to <font class="italic">string</font>.  If it finds
such a symbol, it returns three values: the symbol, <font class="lisp">t</font>, and the package
on which the symbol is interned.  If it does not find one, it returns
<font class="lisp">nil</font>, <font class="lisp">nil</font>, and <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>intern-local-soft <font class='italic' color='purple'>string &optional (pkg <font class="lisp">package</font>)</font></font></font><br>
<font class="lisp">intern</font> searches <font class="italic">pkg</font> (but <font class="italic">not</font> its superpackages), looking
for a symbol whose print-name is equal to <font class="italic">string</font>.  If it finds
such a symbol, it returns three values: the symbol, <font class="lisp">t</font>, and <font class="italic">pkg</font>
If it does not find one, it returns <font class="lisp">nil</font>, <font class="lisp">nil</font>, and <font class="lisp">nil</font>.
</div>

	Each symbol remembers which package it belongs to.  While you can
intern a symbol in any number of packages, the symbol will only remmeber
one:  normally, the first one it was interned in, unless you clobber it.
This package is available as <font class="lisp">(cdr (package-cell-location <font class="italic">symbol</font>))</font>.
If the value is <font class="lisp">nil</font>, the symbol believes that it is uninterned.

	The printer also implicitly uses the value of <font class="lisp">package</font> when
printing symbols.  If slashification is on, the printer tries to print
something such that if it were given back to the reader, the same object would be produced.
If a symbol which is not in the current name space were just printed as
its print name and read back in, the reader would intern it on the wrong
package, and return the wrong symbol.  So the printer figures out the right
colon prefix so that if the symbol's printed representation were read back
in to the same package, it would be interned correctly.  The prefixes
only printed if slashification is on, i.e. <font class="lisp">prin1</font> prints them 
and <font class="lisp">princ</font> does not.

<div class='defun'><font class='exdent'><font class='funcname'>remob <font class='italic' color='purple'>symbol &optional package</font></font></font><br>
<font class="lisp">remob</font> removes <font class="italic">symbol</font> from <font class="italic">package</font> (the names means "REMove from OBarray").
<font class="italic">symbol</font> itself is unaffected, but <font class="lisp">intern</font> will no longer find
it on <font class="italic">package</font>.  <font class="lisp">remob</font> is always "local", in that it removes only from the specified
package and not from any superpackages.  It returns <font class="lisp">t</font> if the symbol was
found to be removed. <font class="italic">package</font> defaults to the contents of the symbol's
package cell, the package it is actually in.  (Sometimes a symbol
can be in other packages also, but this is unusual.)
</div>

<div class='defun'><font class='exdent'><font class='funcname'>mapatoms <font class='italic' color='purple'>function &optional (package <font class="lisp">package</font>) (superiors-p <font class="lisp">t</font>)</font></font></font><br>
<font class="italic">function</font> should be a function of one argument.  <font class="lisp">mapatoms</font> applies
<font class="italic">function</font> to all of the symbols in <font class="italic">package</font>.  If <font class="italic">superiors-p</font> is
<font class="lisp">t</font>, then the function is also applies to all symbols in <font class="italic">package</font>'s
superpackages.  Note that the function will be applied to shadowed symbols
in the superpackages, even though they are not in <font class="italic">package</font>'s name space.
If that is a problem, <font class="italic">function</font> can try applying <font class="lisp">intern</font>
in <font class="italic">package</font> on each symbol it gets, and ignore it if it is not <font class="lisp">eq</font>
to the result of <font class="lisp">intern</font>; this measure is rarely needed.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>mapatoms-all <font class='italic' color='purple'>function &optional (package "<font class="lisp">global</font>")</font></font></font><br>
<font class="italic">function</font> should be a function of one argument.
<font class="lisp">mapatoms-all</font> applies <font class="italic">function</font> to all of the symbols
in <font class="italic">package</font> and all of <font class="italic">package</font>'s subpackages.  Since
<font class="italic">package</font> defaults to the <font class="lisp">global</font> package, this
normally gets at all of the symbols in all packages.
It is used by such functions as <font class="lisp">apropos</font> and <font class="lisp">who-calls</font> (see (apropos-fun))
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(mapatoms-all
  (function
    (lambda (x)
      (and (alphalessp 'z x)
           (print x)))))
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>pkg-create-package <font class='italic' color='purple'>name &optional (super <font class="lisp">package</font>) (size <font class="lisp">200</font>)</font></font></font><br>
<font class="lisp">pkg-create-package</font> creates and returns a new package.  Usually packages are created
by <font class="lisp">package-declare</font>, but sometimes it is useful to create
a package just to use as a hash table for symbols, or for some other
reason.

If <font class="italic">name</font> is a list, its first element is taken as the package name
and the second as the program name; otherwise, <font class="italic">name</font> is taken as both.
In either case, the package name and program name are coerced to strings.
<font class="italic">super</font> is the superpackage for this package; it may be <font class="lisp">nil</font>,
which is useful if you only want the package as a hash table, and don't
want it to interact with the rest of the package system.  <font class="italic">size</font> is
the size of the package; as in <font class="lisp">package-declare</font> it is rounded up
to a "good" size for the hashing algorithm used.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>pkg-kill <font class='italic' color='purple'>pkg</font></font></font><br>
<font class="italic">pkg</font> may be either a package or the name of a package.  The package
should have a superpackage and no subpackages.  <font class="lisp">pkg-kill</font> takes
the package off its superior's subpackage list and refname alist.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>pkg-find-package <font class='italic' color='purple'>x &optional (create-p <font class="lisp">nil</font>) (under "<font class="lisp">global</font>")</font></font></font><br>
<font class="lisp">pkg-find-package</font> tries to interpret <font class="italic">x</font> as a package.
Most of the functions whose descriptions say "... may be either
a package or the name of a package" call <font class="lisp">pkg-find-package</font> to interpret
their package argument.

If <font class="italic">x</font> is a package, <font class="lisp">pkg-find-package</font> returns it.
Otherwise it should be a symbol or string, which is taken to be
the name of a package.  The name is looked up on the refname
alists of <font class="lisp">package</font> and its superpackages, the same as if it had
been typed as part of a colon prefix.  If this finds the package, it
is returned.  Otherwise, <font class="italic">create-p</font> controls what happens.
If <font class="italic">create-p</font> is <font class="lisp">nil</font>, an error is signalled.  Otherwise,
a new package is created, and installed as an inferior of <font class="italic">under</font>.
</div>

	A package is implemented as a structure, created by <font class="lisp">defstruct</font>.
The following accessor macros are available on the <font class="lisp">global</font> package:
.ftable 3 0 1500
.item pkg-name
The name of the package, as a string.
.item pkg-refname-alist
The refname alist of the package, associating strings with packages.
.item pkg-super-package
The superpackage of the package.
.end_table
<div class='section'>4.8 Status Information</div>
	The current package--where your type-in is being interned--is
always the value of the symbol <font class="lisp">package</font>.  A package is a named
structure which prints out nicely, so examining the value of
<font class="lisp">package</font> is the best way to find out what the current package is.
Normally, it should be <font class="lisp">user</font>, except when inside
compilation or loading of a file belonging to some other package.

  To get more information on the current package or any other, use the
function <font class="lisp">pkg-describe</font>.  Specify either a package object or a string
which is a refname for the desired package as the argument.  This will
print out everything except a list of all the symbols in the package.
If you want <font class="italic">that</font>, use <font class="lisp">(mapatoms 'print <font class="italic">package</font> nil)</font>.
<font class="lisp">describe</font> of a package will call <font class="lisp">pkg-describe</font>.

<div class='section'>4.9 Packages, Loading, and Compilation</div>
	It's obvious that every file has to be loaded into the right package
to serve its purpose.  It may not be so obvious that every file must be
compiled in the right package, but it's just as true.  Luckily, this
usually happens automatically.

	When you have mentioned a file in a package's file-alist, requesting
to compile that file with <font class="lisp">qc-file</font> or loading it with <font class="lisp">load</font> automatically
selects that package to perform the operation.  This is done by
inverting the package-to-file correspondence described by the
file-alists and remembering the inversion in the form of <font class="lisp">:package</font>
properties on symbols in the <font class="lisp">files</font> package (the symbol representing the
file is <font class="lisp">(intern (file-expand-pathname <font class="italic">filename</font>) "files"))</font>.

	The system can get the package of a source file from its "editor
property list".  For instance, you can put at the front of your file
a line such as "; -*- Mode:Lisp; Package:System-Internals -*-".  The
compiler puts the package into the QFASL file.
If a file is not mentioned in a package's file-alist and doesn't
have such a package specification in it, the system loads it into
the current package, and tells you what it did.

	To compile or load all of the files of a package, you can use the
<font class="lisp">pkg-load</font> function (see (pkg-load-fun)), which uses the file-alist from the package
declaration.

<div class='section'>4.10 Subpackages</div>
	Usually, each independent program occupies one package, which is
directly under <font class="lisp">global</font> in the hierarchy.  But large programs, such as
Macsyma, are usually made up of a number of sub-programs, which are
maintained by a small number of people.  We would like each
sub-program to have its own name space, since the program as a whole
has too many names for anyone to remember.  So, we can make each
sub-program into its own package.  However, this practice requires
special care.

	It is likely that there will be a fair number of functions and
symbols which should shared by all of the sub-programs of Macsyma.
These symbols should reside in a package named <font class="lisp">macsyma</font>, which would be
directly under <font class="lisp">global</font>.
Then, each part of <font class="lisp">macsyma</font> (which might be called <font class="lisp">sin</font>,
<font class="lisp">risch</font>, <font class="lisp">input</font>, and so on) would have its own package, with the <font class="lisp">macsyma</font>
package as its superpackage.  To do this, first declare the <font class="lisp">macsyma</font>
package, and then declare the <font class="lisp">risch</font>, <font class="lisp">sin</font>, etc. packages, specifying
<font class="lisp">macsyma</font> as the superpackage for each of them.  This way, each
sub-program gets its own name space.  All of these declarations would probably
be in a together in a file called something like "macpkg".

	However, to avoid a subtle pitfall (described in detail in the
appendix), it is necessary that the <font class="lisp">macsyma</font> package itself contain no
files;  only a set of symbols specified at declaration time.  This
list of symbols is specified using <font class="lisp">shadow</font> in the declaration of the
<font class="lisp">macsyma</font> package.  At the same time, the file-alist specified in the
declaration must be <font class="lisp">nil</font> (otherwise, you will not be allowed to create
the subpackages).  The symbols residing in the <font class="lisp">macsyma</font> package can
have values and definitions, but these must all be supplied by files
in <font class="lisp">macsyma</font>'s subpackages (which must "<font class="lisp">extern</font>" those symbols as
necessary).  Note that this is exactly the same treatment that <font class="lisp">global</font>
receives:  all its functions are actually defined in files which are
loaded into <font class="lisp">system-internals (si), compiler</font>, etc.

	To demonstrate the full power and convenience of
this scheme, suppose there were a second huge program called <font class="lisp">owl</font> which
also had a subprogram called <font class="lisp">input</font> (which, presumably, does all of the
<font class="lisp">input</font>ting for <font class="lisp">owl</font>), and one called <font class="lisp">database</font>.  Then a picture of the
hierarchy of packages would look like this:
<pre class="lisp">
			global
			   |
		/--------------------------------\
		|                                |
	     macsyma		                owl
		|                                |
 -----------------------------           -------------------------
  | | |      |       |       |           |         |         | | |
(others)   risch    sin    input       input   database      (others)
</pre>

	Now, the <font class="lisp">risch</font> program and the <font class="lisp">sin</font> program both do integration, and
so it would be natural for each to have a function called <font class="lisp">integrate</font>.
From inside <font class="lisp">sin</font>, <font class="lisp">sin's</font> <font class="lisp">integrate</font> would be referred to as "<font class="lisp">integrate</font>"
(no prefix needed), while <font class="lisp">risch's</font> would be referred to as
"<font class="lisp">risch:integrate</font>".  Similarly, from inside <font class="lisp">risch</font>, <font class="lisp">risch's</font> own
<font class="lisp">integrate</font> would be called "<font class="lisp">integrate</font>", whereas <font class="lisp">sin's</font> would be referred
to as "<font class="lisp">sin:integrate</font>".

	If <font class="lisp">sin</font>'s <font class="lisp">integrate</font> were a recursive function, the implementor would
be referring to it from within <font class="lisp">sin</font> itself, and would be happy that he
need not type out "<font class="lisp">sin:integrate</font>" every time; he can just say
"<font class="lisp">integrate</font>".

	From inside the <font class="lisp">macsyma</font> package or any of its other sub-packages,
the two functions would be referred to as "<font class="lisp">sin:integrate</font>" and as
"<font class="lisp">risch:integrate</font>".  From
anywere else in the hierarchy, they would have to be called
"<font class="lisp">macsyma:sin:integrate</font>" and "<font class="lisp">macsyma:risch:integrate</font>".

	Similarly, assume that each of the <font class="lisp">input</font> packages has a function
called <font class="lisp">get-line</font>.  From inside <font class="lisp">macsyma</font> or any of <font class="lisp">macsyma's</font> subprograms
(other than <font class="lisp">input</font>), the relevant function would be called
<font class="lisp">input:get-line</font>, and the irrelevant one <font class="lisp">owl:input:get-line</font>.  The
converse is true for <font class="lisp">owl</font> and its sub-programs.  Note that there is no
problem arising from the fact that both <font class="lisp">owl</font> and <font class="lisp">macsyma</font> have
subprograms of the same name (<font class="lisp">input</font>).

	You might also want to put Macsyma's <font class="lisp">get-line</font> function on
the <font class="lisp">macsyma</font> package.  Then, from anywehere inside Macsyma, the function
would be called <font class="lisp">get-line</font>; from the <font class="lisp">owl</font> package and subpackages
it could be referred to as <font class="lisp">macsyma:get-line</font>.

<div class='section'>4.11 Initialization of the Package System</div>
	This section describes how the package system is initialized
when generating a new software release of the Lisp Machine system;
none of this should affect users.

	When the world begins to be loaded, there is no package system.
There is one "obarray", whose format is different from that used by
the package system.  After sufficiently much of the Lisp environment
is present for it to be possible to initialize the package system,
that is done.  At that time, it is necessary to split the symbols of
the old-style obarray up among the various initial packages.

  The first packages created by initialization are the most important
ones:  <font class="lisp">global</font>, <font class="lisp">system</font>, <font class="lisp">user</font>, and <font class="lisp">system-internals</font>.
All of the symbols already
present are placed in one of those packages.  By default, a symbol
goes into <font class="lisp">system-internals</font>.  Only those placed on special lists go
into one of the others.  These lists are the file "AI: LISPM2; GLOBAL &gt;" of
symbols which belong in <font class="lisp">global</font>, the file "AI: LISPM2; SYSTEM &gt;" which
go in <font class="lisp">system</font>, and the file "AI: LISPM2; KWDPKG &gt;" of symbols
which belong in <font class="lisp">user</font> (at the moment, these are actually loaded into
<font class="lisp">global</font>, because not everything has been converted to use colons where
necessary).

	After the four basic packages exist, the package system's
definition of <font class="lisp">intern</font> is installed, and packages exist.  Then, the
other initial packages <font class="lisp">format</font>, <font class="lisp">compiler</font>, <font class="lisp">eine</font>, etc. are declared and
loaded using <font class="lisp">package-declare</font> and <font class="lisp">pkg-load</font>, in almost the normal
manner.  The exception is that a few of the symbols present before
packages exist really belong in one of these packages.  Their package
declarations contain calls to <font class="lisp">forward</font> and <font class="lisp">borrow</font>, which exist only for
this purpose and are meaningful only in package declarations, and are used
to move the symbols as appropriate.  These declarations are kept in
the file "AI: LISPM; PKGDCL &gt;".

<div class='defun'><font class='exdent'><font class='funcname'>globalize <font class='italic' color='purple'>&rest symbols</font></font></font><br>
	Sometimes it will be discovered that a symbol which ought to be in
<font class="lisp">global</font> is not there, and the file defining it has already been loaded,
thus mistakenly creating a symbol with that name in a package which
ought just to inherit the one from <font class="lisp">global</font>.  When this happens, you can
correct the situation by doing <font class="lisp">(globalize "<font class="italic">symbol-name</font>")</font>.  This
function creates a symbol with the desired name in <font class="lisp">global</font>, merges
whatever value, function definition, and properties can be found on
symbols of that name together into the new symbol (complaining if
there are conflicts), and forwards those slots of the existing symbols
to the slots of the new one using one-q-forward pointers, so that they
will appear to be one and the same symbol as far as value, function
definition, and property list are concerned.  They cannot all be made
<font class="lisp">eq</font> to each other, but <font class="lisp">globalize</font> does the next-best thing:  it takes
an existing symbol from <font class="lisp">user</font>, if there is one, to put it in <font class="lisp">global</font>.
Since people who check for <font class="lisp">eq</font> are normally supposed to specify <font class="lisp">user</font>
anyway, they will not perceive any effect from moving the symbol from
<font class="lisp">user</font> into <font class="lisp">global</font>.

	If <font class="lisp">globalize</font> is given a symbol instead of a string as argument,
the exact symbol specified is put into <font class="lisp">global</font>.  You can use this when
a symbol in another package, which should have been inherited from
<font class="lisp">global</font>, is being checked for with <font class="lisp">eq</font>--as long as there are not <font class="italic">two</font>
different packages doing so.  But, if the symbol is supposed to be in
<font class="lisp">global</font>, there usually should not be.
</div>

<div class='section'>4.12 Initial Packages</div>
The initially present packages include:

.table 3
.item global
Contains advertised global functions.
.item user
Used for interning the user's type-in.  Contains all keyword symbols.
.item sys <font class="main">or</font> system
Contains various internal global symbols
used by various system programs.
.item si <font class="main">or</font> system-internals
Contains subroutines of many advertised
system functions.  <font class="lisp">si</font> is a subpackage of <font class="lisp">sys</font>.
.item compiler
Contains the compiler and fasload.  <font class="lisp">compiler</font> is a subpackage
of <font class="lisp">sys</font>.
.item eine
Contains the Eine editor.
.item chaos
Contains the Chaos net controller.
.item supdup
Contains the Supdup program.
.item peek
Contains the Peek program.
.item format
Contains the function <font class="lisp">format</font> and its associated subfunctions.
.end_table

	Packages which are used for special sorts of data:
.table 3
.item fonts
Contains the names of all fonts.
.item files
Contains the file-symbols of all files.
Many properties are kept on these symbols to remember information
about files which are in use.
.item format
Contains the keywords for <font class="lisp">format</font>, as well as the code.
.end_table

Here is a picture depicting the inital package hierarchy:
<pre class="lisp">
                           global
                             |    
  /-----------------------------------------------------------\
  |     |     |         |        |       |       |      |     |
user  eine  chaos    system    supdup  format  fonts  files  peek
                        |
                /--------------\
                |              |
         system-internals    compiler
</pre>

<div class='section'>4.13 Multiple Instantiations of a Program</div>
	This isn't finished yet, which is why we don't say how to do
any of this.

	Suppose a maintainer of EINE (the Lisp Machine editor) has
made some changes to EINE, and would like to debug them.  He has a
problem: if he reads in the new version, which presumably may be full
of bugs, then he will not be able to do any editing!  This would be
annoying, since the editor is very useful.

	We would like both the regular and the experimental versions
of the editor to <font class="italic">both</font> be loaded into the Lisp world.  In order for two
definitions of each editor function to coexist, we need to load the
new version into a separate package, which must have a different name
(not named "<font class="lisp">eine</font>", like the package the original editor is in).  If
the test version's package is called "<font class="lisp">test-eine</font>", then the user can
try it by calling <font class="lisp">(test-eine:ed)</font>, and edit it using <font class="lisp">(ed)</font>.

	However, there is a problem to be faced.  The editor redefines
a few entry-point functions (<font class="lisp">ed</font>, <font class="lisp">edprop</font>, etc) which reside in <font class="lisp">global</font>.
If the test editor redefined them, the whole point of the separate
package would be lost.  So, the <font class="lisp">test-eine</font> package must <font class="lisp">shadow</font> all the
symbols which the regular <font class="lisp">eine</font> package <font class="lisp">extern</font>s.

	Further complications are needed to make it possible to test
one program using another instead of by hand.  Suppose that there is a
program named <font class="lisp">random</font> residing in its own package, and containing a
function named <font class="lisp">number</font>.  Suppose that we have a debugged program <font class="lisp">dp</font>
(Dissociated Press) which uses <font class="lisp">random:number</font>.  And now, we have
written a new version of <font class="lisp">random</font> and want to test it using <font class="lisp">dp</font>, without
installing it and breaking system tools which use <font class="lisp">random</font>.  What we
want to do is to load in a test version of <font class="lisp">random</font>, <font class="lisp">test-random</font>, and
also a <font class="lisp">test-dp</font> which will refer to it, to test it with.

	This can be done if we can make the <font class="lisp">test-dp</font> package
take references to <font class="lisp">random</font> as references to the <font class="lisp">test-random</font>
package.  All this takes is
an entry on <font class="lisp">test-dp</font>'s refname-alist, associating the name "<font class="lisp">random</font>"
with the <font class="lisp">test-random</font> package.  Then, when <font class="lisp">random:number</font> is seen in the
course of reading in the old <font class="lisp">dp</font> program into <font class="lisp">test-dp</font>,
<font class="lisp">test-random:number</font> will actually be used.  Note that normally <font class="lisp">test-dp</font>
wouldn't have an entry on its own refname-alist for "<font class="lisp">random</font>";  it
would inherit the association from <font class="lisp">global</font>.  We are actually
"shadowing" in <font class="lisp">test-dp</font> the definition of "<font class="lisp">random</font>" as a package refname
which is present in <font class="lisp">global</font>.  Here is what we will get.
<pre class="lisp">
                            global  [random -&gt; random]
                               |
      /-----------------------------------------------\
      |        |                      |               |
     dp  =&gt;  random                test-dp  =&gt;      test-random
                           [random -&gt; test-random]
</pre>
("=&gt;" indicates who calls whom;  "-&gt;" indicates a refname).

	So far, every package has had its own name as a refname for
itself.  A test package, however, shouldn't have its actual name as a
refname for itself, but the name its program expects:  "<font class="lisp">random</font>", not
"<font class="lisp">test-random</font>".  This is necessary to handle test packages with
subpackages right, together with shadowing.  In fact every package has
a "program name" as well as a "name".  For ordinary packages, they are
the same, but for a test package, the program name is identical to
that of the original package.

	Suppose we have the Macsyma program with all of its sub-packages as
described above. Further assume that the <font class="lisp">input</font> sub-program's author
has his own symbol named <font class="lisp">simp</font>, and he calls <font class="lisp">macsyma:simp</font>
in various places to get the
one in the <font class="lisp">macsyma</font> package.  Now, say someone wants to load an
experimental <font class="lisp">macsyma</font> into the machine: he would name the new obarray
<font class="lisp">test-macsyma</font> or something.  In order to assure that the reference to
<font class="lisp">macsyma:simp</font> is properly resolved, the refname-alist of <font class="lisp">test-macsyma</font>
must contain <font class="lisp">test-macsyma</font> under the name <font class="lisp">macsyma</font>.  This, finally,
is the reason why each package has a reference to itself on its refname-alist.
.eof
</body>
</html>

